Atlassian Integration Guide : Dragons Stage 2 - Install JIRA
This page last changed on Mar 22, 2011 by alui.


Beware of fiends and dragons on the gargoyled eaves. You are embarking on stage 2 of the Atlassian Dragon Quest.

In this stage, you will install Atlassian JIRA for bug tracking and issue management. You will also hook JIRA up to Crowd, for SSO and centralised user management.

Time estimate: This stage will take approximately 60 minutes.

On this page:

Step 1. Create your JIRA Database in PostgreSQL

Now you will create a database where the Atlassian JIRA application will store its data, and the user that JIRA will use to connect to the database. We are assuming that you have already created your PostgreSQL database server in Dragons Stage 1.

We are using pgAdmin III, the administration user interface supplied with PostgreSQL. If you used the one-click installer when installing PostgreSQL, pgAdmin III will be already installed on your computer.

  1. Start pgAdmin III.
  2. Add a new login role called 'jirauser':
    • Right-click 'Login Roles' and select 'New Login Role'.
    • Enter the role 'Role name': jirauser.
    • Enter a 'Password' and enter it again to confirm it.
    • Click the 'Role privileges' tab.
    • Select 'Can create database objects'.
    • Select 'Can create roles'.
    • Click 'OK' to create the user.
  3. Add a new database called 'jira':
    • Right-click 'Databases' and select 'New Database'.
    • Enter the database 'Name': jira.
    • Select the 'Owner': jirauser.
    • Click 'OK' to create the database.

Alternatively, If you are on UNIX and do not have pgAdmin III, you can use the command line interface instead. Assuming that you are using the default installation directory of /opt/PostgreSQL/8.4/bin/, enter the following commands:

sudo -s -H -u postgres
# Create the JIRA user:
/opt/PostgreSQL/8.4/bin/createuser -S -d -r -P -E jirauser
# Create the JIRA database:
/opt/PostgreSQL/8.4/bin/createdb -O jirauser jira
exit

Screenshot 1 (click to enlarge): JIRA database and user in PostgreSQL

Step 2. Install JIRA

Requirements: JIRA 4.3.
Do not use the 'Windows Installer' for this integration exercise. Please make sure you follow the instructions below to download the 'Standalone (ZIP Archive)' file.

For Windows: (click to expand)
  1. Go to the Atlassian download centre.
  2. Click the 'Show all' link above the download buttons, to see all the download file types.
  3. Download the 'Standalone (ZIP Archive)' file for JIRA 4.3.
    Do not use the 'Windows Installer' for this integration exercise, because the workflow for configuring an external database is simpler when installing from the zip archive.
  4. Unpack the zip archive into a directory of your choice, avoiding spaces in the directory name.
  5. Run the JIRA Configuration Tool at {JIRA_INSTALL}\bin\config.bat
    • Tell JIRA where to put its JIRA Home directory under the 'JIRA Home' tab. For example: C:/data/jira-home
    • Configure the database connection under the 'Database' tab.
      • Database type: PostgreSQL.
      • Hostname – Enter the name or IP address of the server that you installed your PostgreSQL database on, i.e. localhost.
      • Port – Enter the default port that you set up PostgreSQL with, i.e. 5432.
      • Database – This is the name of the database that you created in step 1 above, i.e. jira.
      • Username – This is the user you created in step 1 above, i.e. jirauser.
      • Password – Enter the password you chose in step 1 above.
      • Schema – Accept the default 'public' schema.
  6. Click the 'Test Connection' button to test the connection settings. The tool will attempt to connect to the database, and give a message with the results.
  7. Accept the default 'Pool Size' setting.
  8. Click 'Save' when you have a working connection and click 'Close'.
  9. Start your JIRA server by running {JIRA_INSTALL}\bin\startup.bat.
For UNIX or Linux: (click to expand)
  1. Go to the Atlassian download centre.
  2. Click the 'Linux' tab and download the 'Standalone (TAR.GZ archive)' file for JIRA 4.3.
  3. Unpack the archive into a directory of your choice, avoiding spaces in the directory name.
  4. Run the JIRA Configuration Tool at {JIRA_INSTALL}/bin/config.sh
    • Tell JIRA where to put its JIRA Home directory under the 'JIRA Home' tab. For example: /usr/local/jira-home/
    • Configure the database connection under the 'Database' tab.
      • Database type: PostgreSQL.
      • Hostname – Enter the name or IP address of the server that you installed your PostgreSQL database on, i.e. localhost.
      • Port – Enter the default port that you set up PostgreSQL with, i.e. 5432.
      • Database – This is the name of the database that you created in step 1 above, i.e. jira.
      • Username – This is the user you created in step 1 above, i.e. jirauser.
      • Password – Enter the password you chose in step 1 above.
      • Schema – Accept the default 'public' schema.
  5. Click the 'Test Connection' button to test the connection settings. The tool will attempt to connect to the database, and give a message with the results.
  6. Accept the default 'Pool Size' setting.
  7. Click 'Save' when you have a working connection and click 'Close'.
  8. Start your JIRA server by running {JIRA_INSTALL}/bin/startup.sh.

Full details are in the JIRA installation guide.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 3. Set Up JIRA

Now you can run JIRA's Setup Wizard and then enable some JIRA features that are required for the later stages in this integration procedure.

  1. To access JIRA, go to your web browser and type this address: http://localhost:8080.
  2. The JIRA Setup Wizard will start up, to guide you through the process of setting up your JIRA server and creating an administration user. Detailed instructions are in the JIRA documentation. Here are the things you need to know for our Dragon Quest:
    • Application Title – Accept the default application title.
    • Mode – Accept the default mode.
    • Base URL – Enter the full website address at which JIRA is running, not just 'localhost'. For example, if your computer name is 'coopers' then the base URL should be: http://coopers:8080. Or specify a website address, such as http://www.foobar.com:8080.
    • Leave all the default directories selected.
    • License – If you do not already have a JIRA license, follow the prompts on the Setup Wizard screen to get an evaluation license key.
      Make sure you have a JIRA 4 license. Existing 3.x licenses will not work.
    • Administrator account – This is the JIRA super user, and should be the same as the Crowd super user entered in Dragons Stage 1. Enter the following information:
      • Username: charlie.
      • Password – Enter a password for the administrator account and enter it again to confirm it.
      • Full name: Charlie of Atlassian.
      • Email address – We recommend that you give your own email address here.
    • Email notifications – For the purposes of the Atlassian Dragon Quest, we recommend that you disable email notifications.
  3. Log in to JIRA with username charlie and perform the following configuration steps:
    1. Turn on the public API and allow unassigned issues:
      • Click 'Administration' in the top navigation bar.
      • Click 'General Configuration' in the left-hand panel (in the 'Global Settings' section).
      • Enter your password as prompted, to confirm that you want administrator access. (Note that the Atlassian applications will request this confirmation at various steps in the process. This guide will not mention this step again.)
      • Click 'Edit Configuration'.
      • Select the 'ON' radio button next to 'Allow unassigned issues'.
      • Select the 'ON' radio button next to 'Accept remote API calls'.
      • Click 'Update'.

Screenshot 2: The JIRA Dashboard when you first log in

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 4. Hook JIRA up to Crowd

In this step you will configure JIRA to use Crowd for SSO and centralised user management. To do that, you will define the JIRA application in Crowd, define the Crowd user directory in JIRA, and configure the SSO property files.

  1. If Crowd is not already running, start it up by running {CROWD_INSTALL}\start_crowd.bat (on Windows) or {CROWD_INSTALL}/start_crowd.sh (on UNIX).
  2. Go to your Crowd URL in your browser, e.g. http://www.foobar.com:8095/crowd.
  3. Log in to Crowd with username charlie.
  4. Click 'Applications' in the top navigation bar.
  5. The 'Application Browser' will appear. Click 'Add Application' in the left-hand menu.
  6. The first screen of the Crowd 'Add Application' wizard will appear. Enter the following information:
    • Application Type: JIRA.
    • Name: jira.
    • Description: Atlassian JIRA.
    • Password – Enter the password that JIRA will use to access Crowd and enter it again to confirm it.
    • URL – Enter the base URL of your JIRA site, e.g. http://www.foobar.com:8080.
    • Click 'Resolve IP Address' to ask Crowd to find the 'Remote IP Address' for you. The value will be something like this: 127.0.0.1.
    • Select the 'Crowd' directory.
    • Select 'Allow all users to authenticate'.
    • Click 'Add Application'.
  7. Check the IP addresses for your JIRA application:
    • Click the 'Remote Addresses' tab.
    • Add your JIRA host name, excluding the 'http://www.' prefix and the ':8080' port number, e.g. foobar.com.
    • If the following IP address is not already present, add it: 127.0.0.1.
  8. Connect JIRA to the Crowd user directory:
    • Go to your JIRA URL in your browser, e.g. http://www.foobar.com:8080.
    • Select 'User Directories' from the 'Users, Groups & Roles' section of the 'Administration' menu.
    • Click 'Add Directory', select type 'Atlassian Crowd' and click 'Next'.
    • The Crowd server configuration screen will appear. Enter the following information:
      • Name – Accept the default value, Crowd Server.
      • Server URL – Enter the web address of your Crowd server, e.g. http://www.foobar.com:8095/crowd
      • Application Name: jira. This is the application name that you used to define JIRA in the Crowd 'Add Application' wizard above.
      • Application Password – Enter the password that you defined for JIRA in the Crowd 'Add Application' wizard above.
      • Crowd Permissions – Select Read/Write.
    • Leave the other settings at their default values and click the 'Test Settings' button to test the connection.
    • When you have a working connection, click 'Save'.
    • The 'User Directories' screen will appear. Now you will move the Crowd directory to the top of the list of directories. Click the blue upward arrow in the 'Order' column next to the 'Crowd Server', so that the Crowd directory moves to the top of the list

      Here is a summary of how the directory order affects the processing:

      • The order of the directories is the order in which they will be searched for users and groups.
      • Changes to users and groups will be made only in the first directory where the application has permission to make changes.
  9. Log out of JIRA, but leave JIRA running. (Click the dropdown arrow next to the name 'Charlie of Atlassian', then select 'Log Out'.)
  10. Log in to JIRA again, with the same username charlie and Charlie's password in Crowd.
    You are now authenticating via Crowd!
  11. Leave Crowd up and running, but shut down JIRA. (Press Ctrl+C in your JIRA server command window or run {JIRA_INSTALL}\bin\shutdown.bat (on Windows) or {JIRA_INSTALL}/bin/shutdown.sh (on UNIX).)
  12. Configure the JIRA property files for SSO:
    • Edit the {JIRA_INSTALL}/atlassian-jira/WEB-INF/classes/seraph-config.xml file.
    • Comment out the default authenticator node:
    • Uncomment the line that contains the new authenticator:
    • Save the seraph-config.xml file.
    • Copy the crowd.properties file from {CROWD_INSTALL}/client/conf/ to {JIRA_INSTALL}/atlassian-jira/WEB-INF/classes.
    • Edit the {JIRA_INSTALL}/atlassian-jira/WEB-INF/classes/crowd.properties file and change the following properties:
      • application.name: jira
      • application.password – Enter the password that JIRA will use to access Crowd. This must be the same password as you entered in the Crowd 'Add Application' wizard above.
    • Save the crowd.properties file.
  13. You now have SSO between JIRA and Crowd! Try it:
    • Start your JIRA server again, and go to your JIRA URL in your browser, e.g. http://www.foobar.com:8080.
    • If you are already logged in to Crowd, you will not need to log in to JIRA. SSO ensures that you are already logged in as charlie.
    • Log out of JIRA.
    • Go to Crowd and click an option. Crowd will prompt you to log in. When you logged out of JIRA, SSO ensured that you logged out of Crowd too.
    • Log in to either JIRA or Crowd. You will be logged in to both.

Screenshot 3: User directories in JIRA

Full details are in the Crowd documentation and the JIRA administrator's guide.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 5. Set up a Project and Create your JIRA Dashboard

In this step you will create some data in JIRA, including a project and an issue, for use in the subsequent stages of this integration procedure. Then you will create your own JIRA dashboard with a couple of gadgets.

  1. Create a project in JIRA:
    • Click 'Administration' in the top navigation bar.
    • Click 'Projects' in the left-hand panel, then click 'Add Project'.
    • Enter the following information:
      • Name: Dragons.
      • Key: DRA.
      • Project Lead: charlie.
      • Description: Atlassian Dragon Quest.
    • Leave the rest of the fields with their default values. Click 'Add'.
  2. Add two versions (1.0 and 2.0):
    • Click 'Manage versions'.
    • Enter the following information then click 'Add':
      • Version Name: 1.0.
      • Description: Version 1.0.
    • Follow the same steps to add Version 2.0.
  3. Add an issue to your project:
    • Click 'Create Issue' at top right of the screen, select the following options then click 'Create':
      • Project: Dragons.
      • Issue Type: Bug.
    • Enter the following information about your new issue then click 'Create':
      • Summary: Dragon slayer's equipment is defective
      • Affects Version/s: 1.0.
      • Assignee: Charlie of Atlassian – Click 'Assign to me'.
      • Description: There's a hole in the dragon slayer's water bucket.
      • Original Estimate: 1d.
    • You now have an issue with a key of 'DRA-1'.
  4. Create a new dashboard for all your dragon-related tasks, issues and general fire fighting:
    • Click 'Dashboards' at top left of your JIRA screen.
    • Click 'Tools' at top right of the screen, then 'Create Dashboard'.
    • The 'Create New Dashboard' screen will appear. Enter the following information:
      • Name: Dragon Development Dashboard.
      • Description: A dashboard for dragon slayers, fire fighters and like-minded brave souls.
    • Leave the other fields at their default values and click the 'Add' button at the bottom of the 'Create New Dashboard' screen (not the one next to 'Add Shares').
  5. You now have a new, empty dashboard. Add the 'Projects' gadget to the dashboard:
    • Click 'Add Gadget'.
    • The 'Gadget Directory' will appear, showing a list of the available gadgets for your JIRA dashboard. Enter 'projects' into the search box at top right of the Gadget directory screen.
    • The list of gadgets will change, to show only the gadgets that match your search term. Find the 'Projects' gadget and click 'Add it Now'. The gadget will be highlighted for a short time and the button's wording will change to 'Adding', while JIRA adds the gadget to the dashboard.
  6. Find and add the 'Assigned To Me' gadget in the same way.
  7. Click 'Finished' to go back to your dashboard.
  8. Drag the 'Assigned to Me' gadget to the top right of your dashboard:
    • Move your mouse pointer over the gadget's blue title bar.
    • The cursor icon will change to a four-pointed arrow. Click the gadget title bar with the left mouse button then drag the gadget to the right. Drop it in the space labelled 'Drag your gadget here.'
  9. Configure the 'Assigned to Me' gadget to point to your 'Dragons' project:
    • Refresh the dashboard, if necessary, to show the 'Number of Results' and other configuration fields in the gadget.
    • Leave the default values as configured for 'Number of Results' and 'Columns to display'.
    • Click the dropdown arrow next to 'Refresh Interval' and select 'Every 15 Minutes'.
    • Click 'Save'.
  10. Configure the 'Projects' gadget:
    • Leave the default values as configured for 'Projects', 'View' and 'Number of Columns'.
    • Click the dropdown arrow next to 'Refresh Interval' and select 'Every 15 Minutes'.
    • Click 'Save'.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Victory!

You can now see your project dashboard with 2 gadgets on it! The 'Projects' gadget shows the project lead Charlie of Atlassian. The 'Assigned to Me' gadget shows the single DRA-1 issue assigned to Charlie.

Screenshot 4 (click to enlarge): JIRA dashboard with 2 gadgets

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.
Don your Chain Mail and Move to the Next Stage

Attachments:
JIRADashboardOnLogin.png (image/png)
Dragon-Banner-2-700px.png (image/png)
JIRADashboardOnLogin.png (image/png)
JIRADashboardOnLogin.png (image/png)
JIRADashboardOnLogin.png (image/png)
JIRADashboardOnLogin-v5.png (image/png)
Document generated by Confluence on May 22, 2011 21:55